CAC Basic API

Objective

The CAC Basic API returns information about a company, including its registration date, company address, and more.

Info

The Corporate Affairs Commission (CAC) is a Nigerian government body responsible for regulating and managing companies in the country. The CAC assigns a Registration Certificate (RC) number to each business that registers with them.

Input	Output
The RC Number or name of the company	The details corresponding to the given RC. The complete list of output fields is provided under the Success Response Details section.

API Endpoint

cacBasic

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the complete information on the parameter used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`RC`	The company's name or RC Number	Mandatory	Not Applicable	Not Applicable

Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/cacBasic' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "RC": "<Enter_RC_number>"
}'

Success Response

The following code is a success response from the API.

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "status": "<Status_Of_Lookup>",
        "message": "<Message_Describing_Result>",
        "timestamp": "<Timestamp_Of_Lookup_in_ISO8601_Format>",
        "data": [
            {
                "classificationId": "<Classification_Id>",
                "natureOfBusinessName": "<Nature_Of_Business_Name>",
                "delistingStatus": "<Delisting_Status>",
                "companyTypeName": "<Company_Type_Name>",
                "id": "<Unique_Company_Id>",
                "headOfficeAddress": "<Head_Office_Address>",
                "active": "<Is_Company_Active>",
                "businessCommencementDate": "<Business_Commencement_Date>",
                "registrationApproved": "<Is_Registration_Approved>",
                "objectives": "<Company_Objectives>",
                "branchAddress": "<Branch_Office_Address>",
                "registrationDate": "<Company_Registration_Date>",
                "approvedName": "<Approved_Company_Name>",
                "classification": "<Company_Classification>",
                "city": "<City>",
                "lga": "<Local_Government_Area>",
                "rcNumber": "<Registration_Certificate_Number>",
                "email": "<Company_Email_Address>",
                "address": "<Complete_Company_Address>",
                "state": "<State>"
            }
        ]
    },
    "metaData": {
        "requestId": "<Unique_Request_Id>",
        "transactionId": "<Transaction_Id>"
    }
}

Success Response Details

Parameter	Type	Description
status	string	The status of the API response
statusCode	integer	The HTTP status code of the API response
result	object	The object containing details about the lookup result
status	string	The status of the lookup operation
message	string	The message describing the result of the lookup operation
timestamp	string	The date and time when the operation was completed, formatted in ISO 8601 standard (YYYY-MM-DDTHH:MM:SS.sssZ)
data	array	The array containing company details
classificationId	integer	The numeric identifier representing the classification category of the business
natureOfBusinessName	string	The nature of the business
delistingStatus	string	The delisting status of the company; whether the company has been delisted or not
companyTypeName	string	The type of company, for example, a limited liability, or sole proprietorship
id	integer	The unique identifier of the company
headOfficeAddress	string	The address of the company's head office
active	boolean	Indicates if the company is currently active
businessCommencementDate	string	The date when the business officially commenced operations
registrationApproved	boolean	Indicates if the company's registration is approved
objectives	string	The description of the company's objectives
branchAddress	string	The address of any branch office of the company
registrationDate	string	The date when the company was registered, formatted in ISO 8601 standard
approvedName	string	The approved name of the company
classification	string	The classification of the company
city	string	The city where the company is located
lga	string	The Local Government Area(LGA) of the company's location
rcNumber	string	The RC number assigned to the company by the CAC
email	string	The email address of the company
address	string	The physical address of the company, including details like street and building
state	string	The state where the company is located
metaData	object	The object containing metadata about the request
requestId	string	The unique identifier for the request
transactionId	string	The transaction ID associated with the request

Error Responses

Input Validation Error - Empty RC
Missing/Invalid Credentials
Input Validation Error - Mismatch Input Length
Invalid Company Name or RC Number
Internal Server Error

{
    "message": "RC is not allowed to be empty",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "message": "We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again",
    "statusCode": 404,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again",
    "statusCode": 404,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	RC is not allowed to be empty	The RC field in the request is empty
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again.	The input length or data provided does not match any existing records
404	We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again.	The entered name or RC number for the company is invalid
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

Objective​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​